Python Architect

• [recommended] packer.py archive block skips _sanitize_bundle_name and ensure_path_within that plugin_exporter.py applies for both formats (src/apm_cli/bundle/packer.py:276)
  plugin_exporter.py applies three layered guards before writing an archive: (1) _sanitize_bundle_name(pkg_name/pkg_version), (2) ensure_path_within(bundle_dir, output_dir), (3) ensure_path_within(archive_path, output_dir) for each branch. packer.py constructs archive_path directly from raw pkg_name and pkg_version with none of these guards. A pkg_name value of ../evil would produce an archive_path that escapes output_dir silently.
  Suggested: Add ensure_path_within import to packer.py. Apply _sanitize_bundle_name to pkg_name/pkg_version, then call ensure_path_within(archive_path, output_dir) in both branches, mirroring plugin_exporter.py:646-649 and plugin_exporter.py:653/661.

• [recommended] Identical archive-writing blocks in packer.py and plugin_exporter.py have already drifted; extract a shared _write_archive helper (src/apm_cli/bundle/packer.py:276)
  packer.py:276-294 and plugin_exporter.py:650-670 contain functionally identical zip/tar.gz branch code. The only diff is that plugin_exporter.py calls ensure_path_within and packer.py does not -- exactly the divergence that duplicated blocks produce over time.
  Suggested: Extract to _write_archive(bundle_dir, archive_path, archive_format, output_dir) that calls ensure_path_within internally, eliminating the security gap by construction.

• [nit] archive_format: str should be Literal['zip', 'tar.gz'] in function signatures and BuildOptions (src/apm_cli/bundle/packer.py:32)
  click.Choice validates at the CLI boundary, but internal callers pass a raw string with no type-checker enforcement. Literal makes the two-value contract explicit to mypy/pyright.
  Suggested: from typing import Literal then Literal['zip', 'tar.gz'] in pack_bundle, export_plugin_bundle, and BuildOptions.bundle_archive_format.

CLI Logging Expert

• [blocking] 'Share with: apm install (bundle).zip' emits a command that does not work (src/apm_cli/bundle/local_bundle.py:134)
  Before this PR, apm pack --archive produced .tar.gz; detect_local_bundle() matches .tar.gz via _looks_like_archive(). After this PR, the default output is .zip, but _looks_like_archive() only returns True for .tar.gz/.tgz -- not .zip. detect_local_bundle() returns None for .zip paths; the install command falls through to registry-install with a confusing unrelated error. local_bundle.py was NOT modified by this PR.
  Suggested: Extend _looks_like_archive() to also match .zip and add the corresponding zip extraction branch to detect_local_bundle() (mirroring the .zip extraction logic already in unpacker.py). Also extend the IM7 guard in install.py to check '.zip'.

• [recommended] --archive-format help text gives no basis for choosing between zip and tar.gz (src/apm_cli/commands/pack.py:179)
  Current: 'Archive format when --archive is set.' The PR body has the right framing (Claude Code compatibility vs legacy CI) but it never reaches the terminal help text.
  Suggested: "Archive format: 'zip' (default, Claude Code and plugin-host compatible; matches apm publish output) or 'tar.gz' (legacy CI pipelines that depended on the previous default)."

• [recommended] Three stale .tar.gz-only references in install.py user-facing strings not updated (src/apm_cli/commands/install.py:1100)
  (1) --as option help at line 1100, (2) example usage at line 1176, (3) --as error message at line 1326 all name only .tar.gz as the accepted archive format.
  Suggested: Change '(directory or .tar.gz produced by apm pack)' to '(directory, .zip, or .tar.gz archive produced by apm pack)'.

• [nit] --archive help cross-reference does not surface the default format (src/apm_cli/commands/pack.py:171)
  Suggested: 'Produce an archive instead of a directory. Default format is .zip (see --archive-format to change).'

• [nit] local_bundle.py module docstring and is_archive docstring still describe .tar.gz as the only archive format (src/apm_cli/bundle/local_bundle.py:4)
  Suggested: Update both to include '.zip or legacy .tar.gz'.

DevX UX Expert

• [recommended] No runtime hint on the silent default-format change: existing scripts will break downstream (src/apm_cli/commands/pack.py)
  apm pack --archive previously produced .tar.gz; it now produces .zip with zero terminal output indicating the change. CI pipelines that run tar xzf *.tar.gz or ls *.tar.gz after pack will fail silently -- APM exits 0, the downstream shell command fails.
  Suggested: In _render_bundle_result or in pack_cmd after a successful archive, emit logger.info or logger.warning when archive=True and archive_format='zip', pointing to --archive-format tar.gz for pipelines that relied on the old default.

• [recommended] --archive-format silently no-ops without --archive; should warn (src/apm_cli/commands/pack.py)
  archive_format is accepted by the CLI and forwarded to pack_bundle() but is only evaluated inside the if archive: guard. Running apm pack --archive-format tar.gz without --archive produces a directory, discards the flag, and exits 0 with no warning.
  Suggested: After effective_target assignment, add: if archive_format != 'zip' and not archive: logger.warning('--archive-format has no effect without --archive').

• [recommended] Three doc surfaces still describe --archive as producing .tar.gz; --archive-format absent from options table (docs/src/content/docs/reference/cli/pack.md)
  (a) pack.md line 32 says --archive produces .tar.gz; --archive-format missing; (b) pack-a-bundle.md line 45 says '.tar.gz instead of a directory'; (c) commands.md line 83 lists --archive but not --archive-format.
  Suggested: Update pack.md --archive row and add --archive-format row. Update pack-a-bundle.md .tar.gz examples to .zip. Add --archive-format to commands.md.

• [nit] --archive help text defers to cross-reference instead of naming the default format (src/apm_cli/commands/pack.py)
  Suggested: help='Produce a .zip archive instead of a directory (use --archive-format tar.gz for legacy pipelines).'

• [nit] --archive-format help text does not explain when to choose each value (src/apm_cli/commands/pack.py)
  Suggested: help='Archive format when --archive is set. Use tar.gz for CI pipelines that relied on the previous default.'

Supply Chain Security Expert

• [recommended] packer.py omits ensure_path_within for archive_path; pkg_name from apm.yml can escape output_dir (src/apm_cli/bundle/packer.py:278)
  plugin_exporter.py calls ensure_path_within(archive_path, output_dir) for both archive format branches. packer.py constructs archive_path directly from output_dir / f'{pkg_name}-{pkg_version}.{ext}' where pkg_name/pkg_version come from apm.yml (user-controlled). A name like ../../cron.d/evil causes archive_path.resolve() to escape output_dir.
  Suggested: After each archive_path assignment (lines 278 and 285), add ensure_path_within(archive_path, output_dir), mirroring plugin_exporter.py:653 and :661.

• [recommended] No uncompressed-size or entry-count guard before zf.extractall; ZIP bomb denial-of-service possible (src/apm_cli/bundle/unpacker.py:67)
  The pre-validation loop checks path safety but never reads member.file_size. A crafted ZIP with high compression ratio can decompress to gigabytes. Python's zipfile imposes no decompression limit.
  Suggested: Accumulate total = sum(m.file_size for m in zf.infolist()) and check entry count. Raise ValueError before extractall if total exceeds a size cap (e.g., 512 MB) or entry count exceeds a count cap (e.g., 10000).

• [recommended] Python 3.12 rglob follows symlinked directories by default; is_symlink() guard misses transitive files on that version (src/apm_cli/bundle/plugin_exporter.py:655)
  APM declares requires-python >= 3.10. In Python 3.12, Path.rglob() changed its default to follow symbolic links to subdirectories. If bundle_dir contains a symlink to an external directory, rglob yields every file inside that external directory; those files have is_symlink() == False and is_file() == True and pass the guard. The old tarfile.add with _tar_filter never recursed into symlinked directories.
  Suggested: After the is_symlink() check, add ensure_path_within(fp, bundle_dir) (catching PathTraversalError and skipping) to reject files reachable only through symlinked directories regardless of Python version.

• [nit] Windows-format ZIP symlink detection via external_attr is a known limitation aligned with Python stdlib (src/apm_cli/bundle/unpacker.py:82)
  The check reads Unix file-type bits; ZIPs created by Windows tools leave the upper 16 bits zero. However, Python's zipfile.extractall() uses the same external_attr mechanism -- the check and the extractor are in sync. No exploitable gap; worth documenting as a known limitation in a code comment.

OSS Growth Hacker

• [recommended] Missing CHANGELOG entry for a default-changing PR -- trust risk for upgrading users
  The [Unreleased] section records the apm publish zip switch but is entirely silent on apm pack --archive now emitting .zip. An operator running apm upgrade has no signal that their artifact filename changed. The escape hatch only helps users who know they need it.

• [recommended] Three docs pages become stale copy-paste traps on merge -- including a live CI command that silently fails
  Confirmed stale: (1) pack.md options table still says .tar.gz; (2) pack-a-bundle.md shows .tar.gz output examples; (3) ci-cd.md contains tar xzf build/*.tar.gz -C ./ which silently fails for upgrading users copying the snippet.

• [nit] The Windows story is the strongest adoption angle and it is unplayed in the PR body
  ZIP is natively extractable on Windows without WSL, GNU tar, or third-party tools. Worth one sentence in the CHANGELOG entry and a phrase in the release note.

Auth Expert -- inactive

No auth files touched; PR changes archive format (zip vs tar.gz) in bundle/packer.py, bundle/plugin_exporter.py, bundle/unpacker.py, commands/pack.py, and core/build_orchestrator.py -- no authentication, token management, credential resolution, or AuthResolver surface is affected.

Doc Writer

• [recommended] CHANGELOG.md has no [Unreleased] entry for the apm pack --archive format change or the new --archive-format flag (CHANGELOG.md)
  Suggested: Add two bullets under ### Added in [Unreleased]: (1) apm pack --archive now produces .zip by default instead of .tar.gz; (2) apm pack --archive-format [zip|tar.gz] escape hatch for legacy CI.

• [recommended] reference/cli/pack.md option table describes --archive as producing .tar.gz and is missing --archive-format (docs/src/content/docs/reference/cli/pack.md)
  Line 32: '--archive | off | Produce a .tar.gz archive instead of a directory.' -- now wrong. --archive-format has no row in the options table.
  Suggested: Update line 32 and add --archive-format [zip|tar.gz] row immediately after. Fix line 53 comment and line 206 reference.

• [recommended] integrations/ci-cd.md and integrations/gh-aw.md show tar xzf restore commands that break against the new .zip default (docs/src/content/docs/integrations/ci-cd.md)
  ci-cd.md line 211: tar xzf build/*.tar.gz -C ./. gh-aw.md line 126: similar claim. These will fail at runtime for upgrading users.
  Suggested: Update restore guidance to unzip -d ./ build/*.zip, or show --archive-format tar.gz explicitly for pipelines requiring tar.gz.

• [recommended] packages/apm-guide/.apm/skills/apm-usage/commands.md -- apm pack options column missing --archive-format (packages/apm-guide/.apm/skills/apm-usage/commands.md)
  Line 83 lists --archive but not --archive-format. This is the authoritative machine-readable CLI summary consumed by agent skills.
  Suggested: Append --archive-format [zip|tar.gz] (default zip) to the apm pack options cell.

• [nit] reference/cli/unpack.md and reference/cli/install.md still describe only .tar.gz as a valid bundle archive format (docs/src/content/docs/reference/cli/unpack.md)
  Suggested: Change 'a .tar.gz archive' to 'a .zip or .tar.gz archive' in unpack.md. Add .zip to packed bundles description in install.md.

Test Coverage Expert

• [blocking] New ZIP-extraction security checks in unpacker.py -- path traversal, absolute path, external_attr symlink -- have no test; tar.gz equivalents are well covered (src/apm_cli/bundle/unpacker.py)
  Probed: (a) grep'd tests/ for 'external_attr' combined with 'unpack_bundle' -- zero matches; (b) read tests/unit/test_unpacker.py in full -- security tests at lines 191 and 205 exercise the directory bundle path, NOT the ZIP extraction path; (c) grep'd for 'zip.*traversal' and 'unpack_bundle.*zip' -- zero hits. By contrast, tar.gz equivalents DO have tests: test_unpack_with_path_traversal_tarball (test_wave4_pure_logic_coverage.py:945), test_unpack_with_symlink_tarball (test_wave4_pure_logic_coverage.py:962).
  Proof (missing): tests/unit/test_unpacker.py::test_unpack_zip_rejects_path_traversal_member -- proves: apm unpack rejects ZIP archives whose member names contain .. or absolute paths, and rejects Unix symlinks stored via external_attr [secure-by-default]

• [recommended] --archive-format tar.gz CLI flag and packer.py tar.gz branch are untested at every tier (src/apm_cli/bundle/packer.py)
  grep'd tests/ for 'archive_format', 'archive-format', 'archive_format.*tar' -- zero matches in executable test code. The unit test test_pack_archive calls pack_bundle(project, out, archive=True) without archive_format, exercising only the default zip branch. packer.py lines 277-283 (the tar.gz branch) has zero test coverage.
  Proof (missing): tests/integration/test_wave6_init_pack_coverage.py::test_pack_archive_format_tar_gz -- proves: apm pack --archive --archive-format tar.gz produces exactly one .tar.gz archive in the build directory, not a .zip [devx, portability]

Performance Expert

• [recommended] ZIP archives are 30-127% larger than tar.gz for typical APM bundle content; the size regression is real and undocumented (src/apm_cli/bundle/packer.py)
  Measured on representative APM bundles: 50 varied files produce ZIP=11.7 KB vs tar.gz=5.1 KB (+127%). Root cause: ZIP DEFLATE resets the compression dictionary at every entry boundary; tar.gz compresses as one stream, benefiting from cross-file pattern matching across YAML/Markdown skill files.
  Suggested: Add a one-line note to the CHANGELOG: 'ZIP archives are typically 30-130% larger than tar.gz for text-heavy skill bundles due to per-file compression; use --archive-format tar.gz when archive size is a priority.'

• [recommended] compresslevel is unset in both ZipFile constructors; default (zlib level 6) is correct but not observable (src/apm_cli/bundle/packer.py:286)
  Both packer.py:286 and plugin_exporter.py:662 call ZipFile without compresslevel. Consider exposing as an internal constant _ZIP_COMPRESS_LEVEL = 6 for observability.

• [recommended] No perf benchmarks accompany the default archive format switch; size and speed trade-offs are unquantified in the PR
  The PR changes the default archive format for all users with no test measuring archive size, pack wall-time, or unpack wall-time. A benchmark comment in the PR body establishes a regression baseline.

• [nit] sorted(bundle_dir.rglob(*)) overhead is negligible -- no change warranted (src/apm_cli/bundle/packer.py)
  Measured at 200 entries: sort overhead = 0.67 ms vs compression I/O phase of 60-321 ms. The sort is valuable for deterministic archive member ordering. No change warranted.

• [nit] Two-pass extraction in unpacker.py is not actually two disk passes (src/apm_cli/bundle/unpacker.py)
  ZipFile.infolist() returns a list populated during init; the central directory is read from disk exactly once. The validation loop iterates an in-memory list. Overhead measured: 0.7 ms for 200 files vs 26.3 ms extraction. Negligible.

• [nit] cleanup_temp handling is correct; no temp dir leak identified (src/apm_cli/bundle/unpacker.py)
  cleanup_temp is set to True and temp_dir is assigned before the try block. Exception handling and the outer finally block both handle cleanup correctly across all branches.

Python Architect

• [blocking] ZIP bomb guard absent in local_bundle._extract_zip_bundle() while present in unpacker.unpack_bundle() at src/apm_cli/bundle/local_bundle.py:201
  Both unpack_bundle() and _extract_zip_bundle() accept user-supplied .zip files and call zf.extractall() after per-member validation. unpacker.py guards with _MAX_ENTRIES=10,000 and _MAX_UNCOMPRESSED=512 MB at lines 85-97. _extract_zip_bundle() applies identical path-traversal and symlink checks but has no bomb guard: apm install evil.zip with 10,001 entries or >512 MB uncompressed will exhaust file descriptors or RAM during extractall(), while apm unpack evil.zip is rejected cleanly.
  Suggested: Add the same guard immediately after zf.infolist() in _extract_zip_bundle(): if len(members) > _MAX_ZIP_ENTRIES or sum(m.file_size for m in members) > _MAX_ZIP_UNCOMPRESSED: shutil.rmtree(temp_dir, ignore_errors=True); return None. Hoist both constants to module level for sharing.

• [recommended] Archive-creation rglob block duplicated verbatim in packer.py section 10 and plugin_exporter.py section 15 at src/apm_cli/bundle/packer.py:277
  Both files contain byte-for-byte identical archive-creation logic: archive_format branch, ensure_path_within() guard, rglob('*') loop with symlink filter, and tarfile.add/zf.write with the same arcname pattern. A future third format requires editing both files; a symlink-filter regression in one will not propagate to the other.
  Suggested: Extract to write_bundle_archive(bundle_dir, output_dir, name, archive_format) -> Path helper in bundle/packer.py.

• [recommended] Three independent ZIP member-validation implementations with diverging safety properties at src/apm_cli/bundle/unpacker.py:65
extractor._safe_extract_zip() checks the full 16-bit Unix mode word; unpacker.py and local_bundle.py check only the upper 4-bit type field. Path-traversal predicates are copy-pasted across files.
  Suggested: Add validate_zip_member(member: zipfile.ZipInfo) -> None to utils/path_security.py and route all three paths through it.

• [nit] _MAX_UNCOMPRESSED and _MAX_ENTRIES defined as block-local variables inside unpacker.py if-branch at src/apm_cli/bundle/unpacker.py:85
  Constants invisible to module-level tooling and cannot be referenced by callers or shared with local_bundle.py.
  Suggested: Hoist to module level: _MAX_ZIP_UNCOMPRESSED = 512 * 1024 * 1024 and _MAX_ZIP_ENTRIES = 10_000.

• [nit] _looks_like_archive() only matches .tar.gz/.tgz -- misleading name at src/apm_cli/bundle/local_bundle.py:135
  A future contributor scanning for archive-type detection will miss the .zip branch dispatched separately.
  Suggested: Rename to _looks_like_tarball().

CLI Logging Expert

• [recommended] No-op warning missing an action hint at src/apm_cli/commands/pack.py
  APM output principle: every warning must include the fix. "--archive-format tar.gz has no effect without --archive" leaves the user to infer the remedy.
  Suggested: logger.warning(f"--archive-format {archive_format} has no effect without --archive -- add --archive to produce a .{archive_format} archive")

• [recommended] ZIP-bomb ValueError reports raw byte integers; human-readable units needed for CI operators at src/apm_cli/bundle/unpacker.py
  "629145600 bytes exceeds 536870912 bytes" requires mental arithmetic. CI operators need MB units to quickly assess severity.
  Suggested: raise ValueError(f"ZIP archive uncompressed size {total_size // (1024 * 1024)} MB exceeds limit of {_MAX_UNCOMPRESSED // (1024 * 1024)} MB")

• [nit] {archive_format!r} renders Python repr quotes in the warning string at src/apm_cli/commands/pack.py
  With archive_format = "tar.gz", !r produces 'tar.gz' with single quotes in user output. Change to bare {archive_format}.

• [nit] Code comment overstates the warning scope at src/apm_cli/commands/pack.py
  Comment: "Warn when --archive-format is set but --archive is not -- the flag is a no-op." But condition is archive_format != "zip", so explicit --archive-format zip without --archive is silently swallowed. Better: "Warn when a non-default --archive-format is given without --archive."

• [nit] ZIP error says "symlink" while tar.gz branch says "symlink/hardlink" -- minor inconsistency at src/apm_cli/bundle/unpacker.py
  Align phrasing across archive format branches. ZIP has no hardlink concept so "symlink" is correct; make error message style consistent with sibling message.

DevX UX Expert

• [recommended] Shipped skill prose for apm install <BUNDLE-PATH> still lists only .tar.gz/.tgz at packages/apm-guide/.apm/skills/apm-usage/commands.md
  Agents loading this skill file at runtime will tell users only .tar.gz archives are supported -- wrong guidance for the new .zip default on day one of merge.
  Suggested: Change "or to a .tar.gz/.tgz archive whose extracted root contains plugin.json" to "or to a .zip, .tar.gz, or .tgz archive whose extracted root contains plugin.json".

• [recommended] --archive-format without --archive should raise click.UsageError, not emit a warning at src/apm_cli/commands/pack.py
  Guard fires only for tar.gz (not explicit zip), producing inconsistent behavior. APM pattern is UsageError for inapplicable flags (--as without a bundle path raises UsageError). Package managers in the reference set (cargo, pip) error on inapplicable flags.
  Suggested: if not archive and ctx.get_parameter_source('archive_format') != click.core.ParameterSource.DEFAULT: raise click.UsageError('--archive-format has no effect without --archive; add --archive to produce an archive.')

• [nit] tar.gz as a period-containing click.Choice string may not complete cleanly in generated shell completions at src/apm_cli/commands/pack.py
  Validate apm pack --archive-format <TAB> completes correctly in bash, zsh, and fish before shipping. Consider aliasing to tgz with help clarifying it means .tar.gz output if completions break.

• [nit] --archive help text cross-references --archive-format, making a simple boolean flag paragraph busy at src/apm_cli/commands/pack.py
  Suggested: "Produce an archive instead of a directory. Default format: .zip. See --archive-format."

Supply Chain Security Expert

• [recommended] ZIP bomb guard absent from local_bundle._extract_zip_bundle() -- asymmetry with unpacker.py at src/apm_cli/bundle/local_bundle.py
apm install <user-supplied-zip> routes through _extract_zip_bundle(). No entry-count or size limit before zf.extractall(). A crafted ZIP with 50,000 entries can exhaust temp-dir disk space while leaving no actionable error message.
  Suggested: Port _MAX_ENTRIES and _MAX_UNCOMPRESSED guard from unpacker.py immediately before zf.extractall() in _extract_zip_bundle().
  Proof (missing at static): grep for bomb guard in local_bundle.py returns zero results; same check confirmed present in unpacker.py lines 85-97.

• [recommended] Bomb guard sums attacker-controlled ZipInfo.file_size, not measured output bytes at src/apm_cli/bundle/unpacker.py
  A crafted ZIP can declare file_size=0 for every entry while DEFLATE stream expands to gigabytes. sum(m.file_size) would be 0 -- passing the 512 MB guard -- while extractall() writes unbounded content. APM-produced ZIPs have accurate metadata, but apm unpack and apm install both accept arbitrary user-supplied archives.
  Suggested: Stream extraction counting bytes written, or enforce RLIMIT_FSIZE on the temp_dir before calling extractall().
  Proof (manual at static): Python docs: ZipInfo.file_size sourced from central directory record, not from decompression. Python's zipfile.ZipFile does not cross-check actual output size against this field.

• [nit] Entry-count and size bomb guard should precede member-iteration loop for early exit at src/apm_cli/bundle/unpacker.py
  A ZIP with 1,000,000 entries triggers 1,000,000 validate_path_segments() calls before the 10,000-entry limit fires. Hoist members = zf.infolist() and the bomb guard immediately inside the with zipfile.ZipFile(...) block before the for-member validation loop.

• [nit] No unit tests cover ZIP bomb guard thresholds at tests/unit/test_unpacker.py
TestUnpackZipSecurity tests path traversal and symlinks but not _MAX_ENTRIES/_MAX_UNCOMPRESSED. If either constant is removed, no test regresses.
  Proof (missing at unit): tests/unit/test_unpacker.py -- proves: bomb guard constants have regression coverage

• [nit] Windows reserved device names (COM1, NUL, CON) pass all path guards at src/apm_cli/bundle/unpacker.py
PureWindowsPath('COM1').drive == '' (falsy), so device names are not caught. Not a traversal bypass but a platform-specific DoS vector on Windows installations.
  Suggested: Add segment-level check: re.compile(r'^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\\..*)?$', re.IGNORECASE) applied to each path segment.

OSS Growth Hacker

• [recommended] apm unpack docs still document .tar.gz exclusively despite this PR adding .zip extraction support at docs/src/content/docs/reference/cli/unpack.md
  Description says "extracts a .tar.gz archive". The PR adds .zip support to unpack_bundle() but the docs don't reflect it. New producers who apm pack --archive and share a .zip will see docs that describe only .tar.gz.
  Suggested: Update Description and first example to show .zip as primary, .tar.gz as legacy.

• [recommended] install.md and commands.md still cite ./bundle.tar.gz as canonical packed-bundle example at docs/src/content/docs/reference/cli/install.md
install.md PACKAGE_REF says "packed bundles (./bundle.tar.gz)". commands.md local-bundle description still names only .tar.gz/.tgz. New users have the wrong extension for a bundle newly produced by apm pack --archive.
  Suggested: Update install.md to list .zip first; update commands.md paragraph.

• [nit] CHANGELOG Changed entry lacks a CI migration one-liner for pipeline maintainers at CHANGELOG.md
  CI pipelines that glob *.tar.gz artifacts will silently break. Append to the bullet: "CI migration: update artifact globs from build/*.tar.gz to build/*.zip, or add --archive-format tar.gz to your apm pack invocation to preserve the previous default."

• [nit] publish.md still documents .tar.gz as auto-pack format (pre-existing drift from feat(publish): switch publish command archive format from tar.gz to zip #1695) at docs/src/content/docs/reference/cli/publish.md
  CHANGELOG references format alignment with apm publish, but publish.md still describes .tar.gz output. Recommend a companion doc-fix PR before the next release note.

Auth Expert -- inactive

No auth-specific files changed. PR is a pure archive-format change with no impact on AuthResolver, token management, credential resolution, or remote-host auth semantics.

Doc Writer

• [recommended] producer/pack-a-bundle.md still describes .tar.gz as the archive output in three places at docs/src/content/docs/producer/pack-a-bundle.md
  Primary producer guide says "Add --archive to get a single .tar.gz", shows .tar.gz inline comment and a distribution example. New users following this guide will look for a file that no longer exists by default.

• [recommended] releasing-from-any-ci.md globs build/*.tar.gz across all four CI examples -- those globs match nothing once --archive produces .zip by default at docs/src/content/docs/producer/releasing-from-any-ci.md
  CI pipeline examples use build/*.tar.gz and build/*.tar.gz.sha256 for sha256 loop and release-create upload. Globs expand to nothing once the default is .zip. Release artifacts silently omitted.
  Suggested: Change all globs to build/*.zip; add --archive to the apm pack call; add a migration callout in the section header.

• [recommended] install.md description still references ./bundle.tar.gz as the packed bundle format at docs/src/content/docs/reference/cli/install.md
  PACKAGE_REF description says "packed bundles (./bundle.tar.gz)". Install examples show only .tar.gz for local bundle with --as.

• [recommended] unpack.md description and all examples reference only .tar.gz at docs/src/content/docs/reference/cli/unpack.md
  BUNDLE_PATH description says "accepts either a .tar.gz archive". All five code examples use bundle.tar.gz. The CHANGELOG states .zip is now supported but docs don't reflect it.

• [recommended] ci-cd.md updates file patterns without a migration callout for existing pipelines at docs/src/content/docs/integrations/ci-cd.md
  The "Pack & Distribute" section silently changes the glob without noting this is a change from previous behavior. Teams with existing pipelines hardcoding *.tar.gz patterns get no warning.
  Suggested: Add a :::note migration callout in the "Pack in CI" subsection.

• [nit] CHANGELOG places --archive-format under ### Changed instead of ### Added at CHANGELOG.md
  Keep a Changelog convention: new flags go in Added. The bullet even starts with "Add".

• [nit] CHANGELOG references apm publish format alignment but publish.md still documents .tar.gz at CHANGELOG.md
  Drop the apm publish cross-reference or open a companion task to update publish.md first.

• [nit] producer/index.md step 4 description still says .tar.gz at docs/src/content/docs/producer/index.md
  Suggested: Change to "apm pack produces a .zip bundle you can ship offline or to a marketplace".

• [nit] concepts/glossary.md bundle definition only mentions .tar.gz at docs/src/content/docs/concepts/glossary.md
  Suggested: "Either a directory or a .zip (default) or .tar.gz archive containing plugin.json at the root."

• [nit] enterprise/security.md local bundle trust model says .tar.gz only at docs/src/content/docs/enterprise/security.md
  Suggested: "apm install <bundle> accepts a directory, .zip, or .tar.gz produced by apm pack."

Test Coverage Expert

• [recommended] No hermetic integration test for apm install <bundle.zip> -- the new default archive format at tests/integration/test_install_local_bundle_e2e.py
test_install_local_bundle_e2e.py tests directory and tarball installs but has no zip test. The full path detect_local_bundle(.zip) -> _extract_zip_bundle() -> install_local_bundle() -> file deployment is untested at integration tier. A regression in the primary distribution path would be invisible until a user reports it.
  Proof (missing at integration-with-fixtures): tests/integration/test_install_local_bundle_e2e.py::TestInstallLocalBundleE2E::test_install_local_bundle_from_zip -- proves: apm install (bundle.zip) deploys plugin bundle files end-to-end [devx,portability-by-manifest]

• [recommended] ZIP bomb guard in unpacker.py has no regression trap at tests/unit/test_unpacker.py
_MAX_ENTRIES=10,000 and _MAX_UNCOMPRESSED=512 MB have no test. If either constant is changed or the guard removed, no test catches the regression.
  Proof (missing at unit): tests/unit/test_unpacker.py::TestUnpackZipSecurity::test_zip_bomb_entry_count_rejected -- proves: apm install (bloated.zip) is rejected before extraction begins [secure-by-default]

• [recommended] TestUnpackZipSecurity is unit tier; path-segment validation on a security surface warrants an integration-with-fixtures CLI-level test at tests/unit/test_unpacker.py
  Unit tests exercise unpack_bundle() directly with real zip files -- genuine protection. But no CLI-level test asserts apm install <traversal.zip> exits non-zero with a user-readable error message.
  Proof (passed at unit): tests/unit/test_unpacker.py::TestUnpackZipSecurity::test_zip_path_traversal_rejected -- proves: unpack_bundle() rejects ZIP path-traversal entries at function level [secure-by-default]

• [nit] --archive-format without --archive emits a warning but no test asserts the warning fires at tests/unit/commands/test_pack_cli_surface.py
  Proof (missing at unit): tests/unit/commands/test_pack_cli_surface.py::TestPackCmdFlags::test_archive_format_without_archive_emits_warning -- proves: --archive-format tar.gz without --archive shows the user a clear warning

Performance Expert

• [recommended] Missing ZIP bomb guard in _extract_zip_bundle() -- asymmetric with unpacker.py at src/apm_cli/bundle/local_bundle.py
_extract_zip_bundle() calls zf.extractall() with no entry-count or size limit. Disk-exhaustion from crafted ZIP via apm install ./crafted.zip on the new primary distribution path.
  Suggested: Port the five-line guard from unpacker.py:85-97 to _extract_zip_bundle().

• [nit] Two separate zf.infolist() calls in unpacker.py -- could be a single merged pass at src/apm_cli/bundle/unpacker.py
  CPython's infolist() returns self.filelist directly; two O(N) passes over the same list is sub-0.1ms for any realistic bundle. Aesthetic tightening only.

• [nit] sorted(bundle_dir.rglob('*')) eagerly materializes all paths before filtering at src/apm_cli/bundle/packer.py
  Negligible at bundle sizes (<200 files). Positive side-effect: deterministic archive entry order. No action required.

• [nit] No compresslevel on ZIP_DEFLATED -- default level 6 is appropriate but undocumented at src/apm_cli/bundle/packer.py
  Suggested: Add comment: # level 6 (zlib default) -- sufficient for agent bundle sizes < 2MB.

Python Architect

• [recommended] ZIP extraction logic triplicated across extractor.py, unpacker.py, and local_bundle.py with inconsistent extraction strategies at src/apm_cli/bundle/unpacker.py:100
  extractor.py._safe_extract_zip() streams each entry via zf.open(info) to an explicitly resolved destination path -- a hardened approach that never calls extractall(). Both new call sites (unpacker.py:100 and local_bundle.py:241) instead validate members inline then call zf.extractall(temp_dir) with noqa S202. This creates two distinct security tiers for nominally identical operations. Any future hardening must be applied in three places.
  Suggested: Extract safe_extract_zip(zf, dest_root) into src/apm_cli/utils/archive.py using the streaming pattern from extractor.py._safe_extract_zip(). Import from unpacker.py and local_bundle.py. Relocate _MAX_ZIP_ENTRIES and _MAX_ZIP_UNCOMPRESSED to the same module.

• [recommended] ZIP and tar.gz creation loops duplicated verbatim in packer.py and plugin_exporter.py at src/apm_cli/bundle/packer.py:293
  The 8-line ZipFile.write block appears identically at packer.py:293-299 and plugin_exporter.py:666-672. The 4-line tarfile.add block is similarly duplicated. Any compression-level or arcname change must be applied to both.
  Suggested: Add _write_zip_archive(bundle_dir, archive_path) and _write_tar_archive(bundle_dir, archive_path) to src/apm_cli/utils/archive.py. Replace both inline blocks with calls to these helpers.

• [recommended] _extract_zip_bundle() returns None on security violations, silently losing the rejection reason at src/apm_cli/bundle/local_bundle.py:218
  When a ZIP bomb limit or path-traversal entry is detected, _extract_zip_bundle() returns None. detect_local_bundle() returns None in turn, and the install command surfaces a generic 'not a local bundle' error. In contrast, unpack_bundle() raises ValueError with a specific message. A user hitting the entry limit gets a confusing error rather than a clear security gate message.
  Suggested: Raise ValueError (or a new LocalBundleSecurityError) from _extract_zip_bundle() instead of returning None for security violations. Reserve None for 'not a ZIP' or 'no plugin.json found'.

• [nit] _MAX_ZIP_ENTRIES and _MAX_ZIP_UNCOMPRESSED constants defined twice in two separate modules at src/apm_cli/bundle/local_bundle.py:46
  _MAX_ZIP_ENTRIES = 10_000 and _MAX_ZIP_UNCOMPRESSED = 512 * 1024 * 1024 appear at unpacker.py:14-15 and local_bundle.py:46-47. A limit change requires two edits.
  Suggested: Define once in utils/archive.py and import in both modules.

• [nit] archive_format validity guard duplicated in packer.py and plugin_exporter.py; already enforced by click.Choice at the CLI layer at src/apm_cli/bundle/packer.py:278
  Both packer.py:278 and plugin_exporter.py:651 contain if archive_format not in ("zip", "tar.gz"): raise ValueError. The valid-format set is defined in three places.
  Suggested: Define SUPPORTED_ARCHIVE_FORMATS = frozenset({"zip", "tar.gz"}) in utils/archive.py and use a single _validate_archive_format(fmt) from both packer.py and plugin_exporter.py.

CLI Logging Expert

• [recommended] Dry-run 'Would pack' line silently drops the archive extension: user sees build/pkg-1.0.0, gets build/pkg-1.0.0.zip at src/apm_cli/bundle/packer.py
  packer.py:196-203 and plugin_exporter.py:548-551 both return the raw bundle_dir as bundle_path in their dry-run early-return paths, ignoring archive=True and archive_format entirely. The live path correctly reassigns result.bundle_path = archive_path. A user running 'apm pack --archive --dry-run' cannot tell which file type will be produced.
  Suggested: In each dry-run early-return, compute the projected archive path when archive=True: dry_path = (output_dir / f"{pkg_name}-{pkg_version}.zip") if (archive and archive_format == "zip") else (output_dir / f"{pkg_name}-{pkg_version}.tar.gz") if archive else bundle_dir.

• [nit] consumer/deploy-a-bundle.md and consumer/index.md still lead with .tar.gz as the primary bundle format
  With .zip now the default output of 'apm pack --archive', these pages are misaligned with what a fresh pack produces. deploy-a-bundle.md lines 6, 12, 47-48 use .tar.gz; consumer/index.md line 21 says 'received a local .tar.gz bundle'.
  Suggested: Update opening prose to 'a directory or .zip (or legacy .tar.gz)' and swap primary code examples to .zip filenames.

DevX UX Expert

• [recommended] --archive help text gives no runtime migration cue to existing .tar.gz automation authors at src/apm_cli/commands/pack.py
  A user whose CI script ran 'apm pack --archive' and then 'tar xzf build/*.tar.gz' will get a silent missing-file error from tar, not from APM. The escape hatch is discoverable via --help but the help text does not signal the default changed.
  Suggested: Change help string to: 'Produce a .zip archive instead of a directory (changed from .tar.gz in this release; use --archive-format tar.gz to restore the previous format for existing CI pipelines).'

• [recommended] ZIP size overhead (30-130% larger) is CHANGELOG-only; not surfaced anywhere in the CLI at pack time at src/apm_cli/commands/pack.py
  A user storing artifacts in size-limited CI storage has no at-runtime hint to try --archive-format tar.gz.
  Suggested: Append to the --archive-format help string: "'tar.gz' is typically 30-130% smaller for text-heavy bundles and preserves the previous default for CI pipelines that rely on it."

• [nit] Success log line does not hint at the size flag
  Suggested: Under the 'Share with: apm install ...' line, add: logger.verbose_detail('Tip: use --archive-format tar.gz for smaller archives on text-heavy bundles.')

• [nit] ci-cd.md switches to bare 'unzip -o build/*.zip -d ./' without noting the --archive-format tar.gz fallback at docs/src/content/docs/integrations/ci-cd.md
  Suggested: Add a comment: '# Migrating from .tar.gz? Add --archive-format tar.gz to the apm pack step above.'

Supply Chain Security Expert

• [recommended] ZIP bomb size guard reads attacker-supplied file_size metadata; actual decompression quota is not enforced at src/apm_cli/bundle/unpacker.py:75
  Both unpacker.py:75 and local_bundle.py:220 compute sum(m.file_size for m in members) against the 512 MB limit. ZipInfo.file_size is a field in the ZIP central-directory header; an attacker declares file_size=0 while deflated content expands to multiple GB. The entry-count guard (10,000) does not bound real disk writes: a 10,000-entry bomb with 50 MB real output per entry yields 500 GB of disk writes while passing both checks.
  Suggested: Enforce a real byte quota during extraction: extract members individually via zf.open(member) and accumulate bytes-read with a running counter, raising ValueError when the running total exceeds _MAX_ZIP_UNCOMPRESSED.

• [nit] noqa: S202 suppression on extractall in unpacker.py lacks inline rationale at src/apm_cli/bundle/unpacker.py:100
  local_bundle.py:241 uses '# noqa: S202 -- validated above' which documents why the suppression is safe. unpacker.py:100 uses '# noqa: S202' with no explanation.
  Suggested: Change to: zf.extractall(temp_dir) # noqa: S202 -- validated above (entry count, size, path traversal, symlink checks)

OSS Growth Hacker

• [recommended] No runtime migration advisory emitted when apm pack --archive now produces .zip instead of .tar.gz at src/apm_cli/commands/pack.py
  Users who upgrade APM and run apm pack --archive in CI will silently get a .zip. Any downstream step globbing build/*.tar.gz matches nothing and may appear to succeed. CHANGELOG discloses the change, but pip-upgrade CI jobs do not read CHANGELOG.
  Suggested: In the pack success path, when archive=True and archive_format='zip', emit a logger.info() line: 'Note: --archive now produces .zip by default (changed in this release). Use --archive-format tar.gz to restore the previous format for legacy pipelines.'

• [recommended] CHANGELOG 'Changed' entry buries the Claude Code hook inside the size-penalty sentence at CHANGELOG.md
  The entry immediately follows the benefit with '30-130% larger'. A skim-reader absorbs 'larger' as the salient fact.
  Suggested: Lead with the benefit ('apm pack --archive now produces .zip, the format Claude Code and plugin hosts natively consume -- no conversion step required, natively extractable on Windows without WSL or tar.'), then a separate 'Note:' bullet for the size disclosure.

• [nit] producer/index.md step 4 description lost format specificity -- 'bundle' is opaque to a new user at docs/src/content/docs/producer/index.md
  Suggested: Change to: 'apm pack produces a .zip you can ship offline or to a marketplace'

• [nit] Windows native-extraction story is underplayed at docs/src/content/docs/producer/pack-a-bundle.md
  Suggested: Add callout near the --archive flag: 'ZIP archives are natively extractable on Windows -- no WSL, tar, or additional tooling required.'

• [nit] Pack success output does not report output file size at src/apm_cli/commands/pack.py
  Suggested: Include the output path and file size in the pack success message when --archive is set.

Doc Writer

• [recommended] consumer/deploy-a-bundle.md not updated: intro and examples still show .tar.gz as the primary bundle format at docs/src/content/docs/consumer/deploy-a-bundle.md:6
  The page opens 'a directory or .tar.gz someone handed you' (line 6); first code example uses apm install ./dist/my-pkg-1.0.0.tar.gz (line 12). Cross-page inconsistency will confuse producers handing ZIP bundles to consumers.
  Suggested: Line 6: 'a directory or .zip someone handed you (or a legacy .tar.gz)'. Line 12 example: use .zip filename. Line 22: 'zip archive (or legacy gzipped tarball)'. Lines 47-48 output block: show .zip path.

• [recommended] CHANGELOG ### Changed entry missing BREAKING: prefix, inconsistent with 0.19.0 apm publish precedent at CHANGELOG.md
  The 0.19.0 release used 'BREAKING:' for the apm publish format change to .zip. The apm pack --archive default change is equally pipeline-breaking.
  Suggested: Prefix the entry: 'BREAKING: apm pack --archive now produces .zip by default instead of .tar.gz.'

• [nit] consumer/index.md routing table row still says '.tar.gz bundle' at docs/src/content/docs/consumer/index.md:21
  Suggested: Change to 'You received a local .zip or .tar.gz bundle and need to install it'

• [nit] CHANGELOG ### Added has an orphan blank line before the --archive-format entry, creating a loose list at CHANGELOG.md
  Suggested: Remove the blank line between the enterprise bootstrap mirror entry and the --archive-format entry in ### Added.

• [nit] releasing-from-any-ci.md reference note says 'tarballs' for what the updated pipeline produces as .zip files at docs/src/content/docs/producer/releasing-from-any-ci.md:89
  Suggested: Change 'per-plugin tarballs' to 'per-plugin bundles'

Test Coverage Expert

• [recommended] _extract_zip_bundle() security guards in local_bundle.py are uncovered; TestUnpackZipSecurity monkeypatches a different module's constants at tests/unit/bundle/test_local_bundle.py
  local_bundle.py defines its own _MAX_ZIP_ENTRIES=10_000 and _MAX_ZIP_UNCOMPRESSED=512MB (lines 46-47). _extract_zip_bundle() uses these guards plus path-traversal, absolute-path, and symlink rejection. TestUnpackZipSecurity monkeypatches apm_cli.bundle.unpacker._MAX_ZIP_ENTRIES and calls unpack_bundle() -- a separate code path. test_local_bundle.py has zero zip, ZipFile, or _MAX_ZIP references. A drift in the checks would be invisible to CI.
  Suggested: Add TestDetectZipBundleSecurity calling detect_local_bundle() with crafted zip fixtures: test_detect_zip_path_traversal_rejected, test_detect_zip_absolute_path_rejected, test_detect_zip_symlink_rejected, test_detect_zip_bomb_entries_rejected (monkeypatching apm_cli.bundle.local_bundle._MAX_ZIP_ENTRIES), test_detect_zip_bomb_size_rejected.
  Proof (missing at unit): tests/unit/bundle/test_local_bundle.py::TestDetectZipBundleSecurity::test_detect_zip_path_traversal_rejected -- proves: apm install bundle.zip rejects a malicious zip containing path-traversal entries without extracting any payload [secure-by-default]

• [recommended] No credential-free integration test for apm install bundle.zip; the only zip install coverage requires a live GITHUB_APM_PAT at tests/integration/test_install_local_bundle_e2e.py
  test_install_local_bundle_e2e.py has test_install_local_bundle_from_tarball for .tar.gz but no zip equivalent. test_pack_unpack_e2e.py::test_full_round_trip covers zip but is gated by pytest.mark.requires_github_token. Per the tier matrix, local bundle install pipeline floor is integration-with-fixtures. ZIP is now the default format.
  Suggested: Add TestInstallLocalBundleE2E::test_install_local_bundle_from_zip: build bundle with _make_plugin_bundle, zip it, call _invoke_install(project, str(zip_path), '--target', 'copilot', monkeypatch=monkeypatch), assert exit_code == 0 and deployed files exist. No network call required.
  Proof (missing at integration-with-fixtures): tests/integration/test_install_local_bundle_e2e.py::TestInstallLocalBundleE2E::test_install_local_bundle_from_zip -- proves: apm install bundle.zip deploys plugin files correctly end-to-end without a live GitHub token [portability-by-manifest]

Performance Expert

• [recommended] ZIP default inflates registry download size 30-40%+ vs tar.gz on every cold install at src/apm_cli/bundle/packer.py
  Benchmark on a realistic 29-file, 162KB-raw skill bundle: tar.gz=28KB, zip=40KB (+40%). ZIP compresses each entry independently, losing cross-file string deduplication from gzip's sliding window. This is a deliberate design trade-off (Windows-native tooling vs compression density), not a bug.
  Suggested: Add compresslevel=9 parameter to ZipFile() in packer.py:293 and plugin_exporter.py:666 to partially recoup the size gap, and surface --archive-format tar.gz in help text as the size-priority alternative.

• [nit] unpacker.py does two O(N) passes over ZIP members; extractor.py does one at src/apm_cli/bundle/unpacker.py
  unpacker.py lines 83-99 loop over all members for validation, then extractall() iterates members again. extractor.py._safe_extract_zip does a single pass: validate, then immediately stream bytes. For typical bundle sizes (<100 files) overhead is <5ms.
  Suggested: Replace the validate-loop + extractall() two-pass with a single-pass pattern matching extractor.py._safe_extract_zip.

• [nit] sorted(bundle_dir.rglob('*')) eagerly materializes the full file list before archiving starts at src/apm_cli/bundle/packer.py
  Both packer.py and plugin_exporter.py force the generator to completion before any bytes are written. For typical APM bundles (<50 files) this is sub-millisecond.
  Suggested: Non-blocking. No action required for this PR.

• [nit] download_archive() holds full archive bytes in memory via response.content at src/apm_cli/deps/registry/client.py
  With ZIP archives 30-40%+ larger, peak memory allocation during install grows proportionally. Pre-existing pattern unchanged by this PR.
  Suggested: Pre-existing issue, not introduced by this PR. Future work: stream-hash on fetch.

Auth Expert -- inactive

No auth-surface files are touched: all changes are in bundle/ (packer, unpacker, local_bundle, plugin_exporter), commands/pack.py, commands/install.py (help text only), core/build_orchestrator.py, deps/registry/client.py (tarball_bytes->archive_bytes format rename, no auth headers), docs pages, and tests -- none of which involve token resolution, credential helpers, AuthResolver, host classification, or HTTP authorization flows.

Python Architect

• [recommended] OSError during zip extraction silently returns None, masking disk/permission failures as non-bundle at src/apm_cli/bundle/local_bundle.py:223
  In _extract_zip_bundle, except (zipfile.BadZipFile, OSError) catches both 'not a zip file' and raw I/O errors from safe_extract_zip's inner file writes. If the temp dir has a permission or disk-full condition, the function returns None instead of propagating -- making detect_local_bundle return None, which causes install.py to fall through to the registry clone path and emit a misleading error. The tar.gz path re-raises all errors after cleanup, making the new zip path asymmetric with the legacy path it sits next to.
  Suggested: Separate 'not a zip' from 'write failed'. Catch only zipfile.BadZipFile for the return-None path; re-raise OSError after cleanup: except zipfile.BadZipFile: shutil.rmtree(temp_dir, ignore_errors=True); return None then except (ValueError, OSError): shutil.rmtree(temp_dir, ignore_errors=True); raise

• [recommended] Migration notice fires on every .zip pack forever with no suppression path at src/apm_cli/commands/pack.py:607
  The info message fires unconditionally on every successful zip-format pack. In CI pipelines that have already migrated, it repeats every build forever with no way to suppress it.
  Suggested: Gate on ParameterSource.COMMANDLINE: only show notice when archive_format was defaulted, not explicitly passed. Plan to drop after one release cycle.

• [nit] validate_archive_format called twice -- explicitly, then inside projected_archive_path at src/apm_cli/bundle/packer.py:286
  Double call is harmless but blurs ownership. Remove the explicit call before projected_archive_path() in both packer.py and plugin_exporter.py.

• [nit] _MAX_ZIP_ENTRIES/_MAX_ZIP_UNCOMPRESSED aliases in unpacker.py and local_bundle.py are pointless indirection at src/apm_cli/bundle/unpacker.py:15
  Import and immediately rebind under private names. Use MAX_ZIP_ENTRIES/MAX_ZIP_UNCOMPRESSED directly at the call sites.

CLI Logging Expert

• [recommended] Migration note fires on every .zip pack forever with no way to suppress it, including when user explicitly passed --archive-format zip at src/apm_cli/commands/pack.py:604
  The guard at line 604 fires unconditionally. A user who already knows and intentionally chose zip sees the migration banner every run. CI pipelines see it every build forever. logger.info is not gated by --verbose.
  Suggested: Compute archive_format_was_defaulted = ctx.get_parameter_source('archive_format') is not click.core.ParameterSource.COMMANDLINE and gate on it.

• [nit] Hardcoded 'in this release' will be stale copy in runtime message and --archive help text at src/apm_cli/commands/pack.py:606
  A relative temporal reference without a version anchor. Drop 'in this release' from both strings.

• [nit] Hand-rolled 'Note:' prefix on logger.info() is redundant with the [i] symbol at src/apm_cli/commands/pack.py:605
  CommandLogger.info() already renders with [i]. Drop the 'Note: ' prefix.

• [nit] verbose_detail size tip duplicates tar.gz guidance already in the info message above it at src/apm_cli/commands/pack.py:609
  In verbose mode two consecutive messages recommend --archive-format tar.gz. Merge into one coherent verbose block.

DevX UX Expert

• [recommended] Migration notice fires unconditionally on every .zip output, even when --archive-format zip was explicitly passed at src/apm_cli/commands/pack.py
  A user who writes apm pack --archive --archive-format zip already knows what they want; the migration notice is backwards noise. No TTL. Violates the 'quiet on the happy path' contract.
  Suggested: Gate on ParameterSource.COMMANDLINE. Plan to drop the notice entirely in the following release.

• [nit] --archive help text embeds release-note copy that belongs in CHANGELOG, not --help at src/apm_cli/commands/pack.py
  Parenthetical '(changed from .tar.gz in this release)' ages poorly.
  Suggested: Trim to: "Produce a .zip archive instead of a directory. Use --archive-format tar.gz for legacy CI pipelines."

Supply Chain Security Expert

• [recommended] Tar.gz backward-compat extraction in unpack_bundle and detect_local_bundle has no decompression-bomb limit on Python <3.12 at src/apm_cli/bundle/unpacker.py
  The new .zip path correctly caps total uncompressed bytes at 512 MB via safe_extract_zip. The parallel .tar.gz backward-compat paths call tar.extractall() directly without a size cap when sys.version_info < (3, 12). A crafted .tar.gz bundle -- the exact format this PR retains for legacy CI -- can exhaust disk or memory with no limit. utils/archive.py already exposes _extract_tar_gz_file() with the size cap.
  Suggested: Import _extract_tar_gz_file from utils.archive and replace the tarfile.open()+extractall() block in unpack_bundle and detect_local_bundle with _extract_tar_gz_file().

• [nit] _zip_member_target does not explicitly reject null bytes in member names at src/apm_cli/utils/archive.py
  The tar path explicitly raises on '\x00' in member_path. Not exploitable but inconsistent with the tar path.
  Suggested: Add early guard: if '\x00' in member_name: _raise(error_type, f'Refusing ZIP entry with null byte: {member_name!r}').

• [nit] Unix-mode symlink check skipped when external_attr == 0 (ZIPs produced on Windows) at src/apm_cli/utils/archive.py
  Not exploitable -- Python's zipfile.open() never materialises symlinks from the data stream. Needs a comment explaining why the short-circuit is safe.

OSS Growth Hacker

• [recommended] Windows-native extraction is the Why do we need a GitHub token? #1 new-user hook but is buried mid-paragraph in pack-a-bundle.md with no visual callout
  Removing the WSL/tar requirement on Windows is a silent adoption unblocker for the enterprise Windows developer segment. Users who land on pack-a-bundle.md via search will miss this entirely.
  Suggested: Add a visually distinct callout block at the top of the --archive section in docs/src/content/docs/producer/pack-a-bundle.md noting Windows native extractability.

• [nit] No story beat planned for a genuinely shareworthy change: Claude Code alignment + Windows unblocking in a single PR
  This PR removes two real blockers simultaneously. The narrative shape is a mini-launch moment. Flag for the next release post.

• [nit] Reference deployment in releasing-from-any-ci.md may show .tar.gz until it upgrades, confusing readers
  Teams clicking through the reference deployment will see .tar.gz and wonder if the doc or code is wrong.

Auth Expert -- inactive

No auth surfaces appear in the diff; all 37 changed files are confined to archive-format handling, and the zip-vs-tar.gz format switch introduces no credential, token, or host-resolution logic.

Doc Writer

• [recommended] releasing-from-any-ci.md silently changed all *.tar.gz references to *.zip with no in-page migration note at docs/src/content/docs/producer/releasing-from-any-ci.md
  The canonical CI release-pipeline reference now outputs .zip with no explanation. Teams upgrading from a release that defaulted to .tar.gz will have broken CI pipelines (sha256sum, upload globs, artifact names) with no in-page text telling them why.
  Suggested: Add a :::note[Breaking change: --archive now produces .zip]::: callout after the canonical sequence block. State the old default, new default, and escape hatch.

• [recommended] reference/cli/pack.md Options table embeds release-scoped language in the permanent --archive description at docs/src/content/docs/reference/cli/pack.md
  The parenthetical '(changed from .tar.gz)' is release-relative language -- stale noise in six months.
  Suggested: Strip the parenthetical. Add a :::note[Migrating from .tar.gz]::: callout in the Behavior section.

• [recommended] ci-cd.md migration hint for a breaking change is buried inside a YAML code comment at docs/src/content/docs/integrations/ci-cd.md
  Code comments are easy to skim past and invisible to copy-paste users. A BREAKING CHANGE deserves a structured Starlight callout.
  Suggested: Replace the inline code comment with a :::caution[Breaking change: default archive format changed to .zip]::: callout.

• [nit] CHANGELOG claims ZIP is 30-130% larger than tar.gz but this range has no backing benchmark at CHANGELOG.md
  The specific range implies measurement. Either remove the range or reference a benchmark.

• [nit] pack.md Behavior section does not document the runtime info note emitted on every .zip pack at docs/src/content/docs/reference/cli/pack.md
  The CLI emits an INFO message post-success that users reading the reference doc will not find documented.

Test Coverage Expert

• [recommended] write_zip_archive / write_tar_archive symlink exclusion in utils/archive.py has no direct test at src/apm_cli/utils/archive.py
  Packer-level tests exercise symlink scanning upstream but do not inject a symlink into the assembled bundle_dir before calling write_zip_archive. Grep confirms zero hits for either function name in the test tree.
  Proof (missing): tests/unit/utils/test_archive.py::test_write_zip_archive_excludes_symlinks -- proves: apm pack --archive does not include symlinks from the assembled bundle directory in the produced zip output [secure-by-default]
  assert 'link.txt' not in zipfile.ZipFile(result).namelist()

• [recommended] tar.gz escape-hatch (--archive-format tar.gz) is not integration-tested as a pack->install round-trip at src/apm_cli/bundle/packer.py
  No test chains pack_bundle(archive=True, archive_format='tar.gz') output through detect_local_bundle and install_local_bundle. The e2e test only globs for *.zip.
  Proof (missing): tests/integration/test_install_local_bundle_e2e.py::test_install_local_bundle_from_pack_tar_gz -- proves: apm install ./bundle.tar.gz works when the tarball was produced by apm pack --archive --archive-format tar.gz [portability-by-manifest,devx]
  assert _invoke_install(consumer, str(result.bundle_path)).exit_code == 0

• [nit] Corrupt zip -> None + temp-dir cleanup path in _extract_zip_bundle is not tested at src/apm_cli/bundle/local_bundle.py
  TestDetectZipBundleSecurity covers path-traversal, symlinks, bombs -- but not a corrupt (BadZipFile) payload.
  Proof (missing): tests/unit/bundle/test_local_bundle.py::test_detect_zip_corrupt_returns_none_and_cleans_temp_dir
assert detect_local_bundle(corrupt_zip_path) is None

Performance Expert

• [recommended] write_zip_archive uses compresslevel=9, adding ~21% CPU overhead for ~0.2% size reduction vs compresslevel=6 at src/apm_cli/utils/archive.py
  CPython 3.12 benchmarks on 35 real APM source files (219 KiB uncompressed): compresslevel=9 takes 11.70ms; compresslevel=6 takes 9.65ms. +2.05ms (+21% CPU) for -160 bytes (-0.2% size). Level 6 is the standard zlib inflection point where the compression curve flattens.
  Suggested: Change compresslevel=9 to compresslevel=6 in write_zip_archive. For write_tar_archive, use tarfile.open(archive_path, 'w:gz', compresslevel=6).

• [nit] sorted(bundle_dir.rglob('*')) materializes the full path list before compression starts
  0.67ms sort overhead for a 170-file bundle. Acceptable cost for reproducible archive ordering. No change recommended.

• [nit] safe_extract_zip chunk size upgrade from 64 KiB to 1 MiB is a net positive; deserves a comment documenting the deliberate choice.

Python Architect

• [recommended] _raise typed -> None instead of -> NoReturn; dead code after bomb-limit calls invisible to type checkers at src/apm_cli/utils/archive.py
  archive.py defines _raise(error_type, message) -> None as a helper that always raises. Because typed -> None (not -> NoReturn), type checkers treat statements following each _raise(...) call as reachable. In safe_extract_zip, the lines after the bomb-limit _raise -- fh.write(chunk) and total_uncompressed = next_total -- are unreachable at runtime but appear reachable to static analysis.
  Suggested: from typing import NoReturn and annotate def _raise(error_type: type[_ErrorT], message: str) -> NoReturn: raise error_type(message)

• [recommended] Fragile message-string inspection to classify ArchiveError in unpacker.py .tar.gz backward-compat path at src/apm_cli/bundle/unpacker.py
if "path" in msg or "Symlinks" in msg or "links" in msg is brittle; both branches raise ValueError anyway. A future wording change to any ArchiveError message in archive.py silently breaks the classification without a test failure.
  Suggested: except ArchiveError as exc: shutil.rmtree(temp_dir, ignore_errors=True); raise ValueError(str(exc)) from exc

• [nit] Redundant validate_archive_format calls in packer.py and plugin_exporter.py (Click already validates the value; projected_archive_path validates internally too)

• [nit] Module-level requests.Session() creation eagerly couples all bundle callers to the network dependency at src/apm_cli/utils/archive.py
  Every pack/unpack/local-bundle import initializes a Session. Move to a lazy singleton _get_archive_session() accessor.

• [nit] Alias chain _MAX_UNCOMPRESSED_BYTES = MAX_ZIP_UNCOMPRESSED -> _MAX_ARCHIVE_DOWNLOAD_BYTES at src/apm_cli/utils/archive.py
  Download size and extraction size have different semantic roles; define as independent named constants.

CLI Logging Expert

• [recommended] Migration notice fires permanently on every invocation -- no expiry or once-seen gate at src/apm_cli/commands/pack.py
  Every apm pack --archive call without --archive-format emits the notice indefinitely. The --archive help text already carries the disclosure. Recommended: remove the runtime notice or gate it to a version-bound transition window.

• [recommended] Migration notice uses logger.info ([i]) instead of logger.warning ([!]) for a pipeline-breaking behavior change at src/apm_cli/commands/pack.py
  A format change from .tar.gz to .zip can silently break CI pipelines. [i] blue reads as low-priority; [!] yellow registers as "pay attention."
  Suggested: Change to logger.warning("--archive now produces .zip by default. Use --archive-format tar.gz to restore the previous format for legacy pipelines.")

• [nit] Migration notice buried after per-file verbose list in --verbose mode; move if show_zip_migration_notice block before the for-f loop at src/apm_cli/commands/pack.py

• [nit] First segment of UsageError is an f-string with no interpolation (remove the f prefix from the first segment) at src/apm_cli/commands/pack.py

DevX UX Expert

• [recommended] click.Choice is case-sensitive: --archive-format TAR.GZ silently fails with a confusing error at src/apm_cli/commands/pack.py
  Users typing TAR.GZ or Zip get "Invalid value for '--archive-format'" for a two-value enum. One-character fix.
  Suggested: type=click.Choice(["zip", "tar.gz"], case_sensitive=False)

• [recommended] Migration notice fires on every invocation, not once -- noisy in CI at src/apm_cli/commands/pack.py
  No persistent seen-state. Options: write a seen-marker to a config dir, or emit as logger.warning so pipelines that suppress warnings can opt out.

• [recommended] --archive-format help text is ~250 chars -- wraps badly in a standard terminal at src/apm_cli/commands/pack.py
  Reference tools keep option help to ~120 chars. Size trade-off detail already appears in CHANGELOG and docs migration caution blocks.

• [nit] Migration notice appears after success line; emit before logger.success or upgrade to logger.warning for higher visual weight

• [nit] Verbose tip leads with size benefit instead of CI-compat rationale; help text and PR body correctly lead with CI compatibility

Supply Chain Security Expert

• [recommended] Null-byte zip entry filename bypasses the error_type parameter and leaks a raw ValueError to callers at src/apm_cli/utils/archive.py
  _zip_member_target has no null-byte guard; Path.resolve() raises plain ValueError before _raise() fires, violating the error_type API contract for ArchiveError callers including the download pipeline. No file is extracted so there is no security bypass, but the error_type API contract is broken and download pipeline error handling breaks for this input class.
  Suggested: if "\x00" in member_name: _raise(error_type, f"Refusing to extract path with null byte: {member_name!r}")
  Proof (missing at unit): tests/unit/utils/test_archive.py::test_extract_zip_rejects_null_byte_member_name -- proves: zip entry with null-byte filename rejected with caller-specified error_type [secure-by-default]

• [nit] No zip-path test for Windows drive-letter or UNC entry names despite PureWindowsPath guards at tests/unit/utils/test_archive.py
  tests/unit/bundle/test_tar_windows_absolute_path.py covers tar.gz; parallel tests needed for zip PureWindowsPath.drive checks.

• [nit] Zip extraction branch in unpacker.py uses bare except Exception instead of translating to ValueError like the tar.gz branch at src/apm_cli/bundle/unpacker.py

• [nit] _extract_zip_bundle collapses mid-extraction OSError into silent None return at src/apm_cli/bundle/local_bundle.py
  Disk-full ENOSPC returns None instead of surfacing the real cause. Separate BadZipFile (-> None) from OSError (-> raise).

OSS Growth Hacker

• [recommended] CHANGELOG BREAKING entry ends on size disclaimer -- narrative inversion converts upgrade enthusiasm into migration anxiety at CHANGELOG.md
  Current text ends: "ZIP archives are typically 30-130% larger..." Reorder to lead with Claude Code format parity and Windows CI win; move size note to conditional escape-hatch mention.

• [recommended] CI docs caution blocks frame the .zip switch as migration burden only -- miss the Windows CI win story at docs/src/content/docs/integrations/ci-cd.md
  Windows CI developers reaching these docs after a pipeline break see only the escape hatch. Prepend one-line positive framing: "ZIP archives extract natively on Windows runners without WSL or a tar binary and match the format Claude Code plugin hosts expect."

• [nit] Added/Changed CHANGELOG section ordering: escape hatch entry appears before the BREAKING change that motivates it

• [nit] In-terminal migration notice has no pointer to docs for headless terminal operators

• [nit] No pre-composed launch one-liner for release post: "APM bundles now speak Claude Code natively -- and unzip on any Windows runner without WSL."

Doc Writer

• [recommended] ci-cd.md caution "instead of switching the restore step to unzip" implies fully migrating to .zip is wrong at docs/src/content/docs/integrations/ci-cd.md
  Rephrase to present both valid paths: add --archive-format tar.gz OR update the upload glob and restore step to .zip.

• [recommended] CHANGELOG Added entry for --archive-format and BREAKING Changed entry describe one behavioral unit but lack cross-reference at CHANGELOG.md
  A reader scanning only ### Added sees the flag without the motivating breaking change. Move the UsageError sentence into the Changed BREAKING entry or add a cross-reference.

• [nit] producer/index.md step 4 says "produces a .zip" but without --archive it produces a directory at docs/src/content/docs/producer/index.md

• [nit] pack.md flag table --archive row buries migration guidance inside feature-description cell; migration caution block below the table already owns this at docs/src/content/docs/reference/cli/pack.md

• [nit] pack-a-bundle.md mentions --archive-format tar.gz without cross-link to CLI reference at docs/src/content/docs/producer/pack-a-bundle.md

• [nit] gh-aw.md does not clarify whether apm-action handles .zip natively or delegates to apm install at docs/src/content/docs/integrations/gh-aw.md

Test Coverage Expert

• [recommended] No test exercises apm install evil.zip to click.UsageError("Bundle security check failed: ...") through the CLI at src/apm_cli/commands/install.py
  Unit tests verify detect_local_bundle raises ValueError (passed, unit tier). No test exercises the CLI boundary. A future refactor in archive.py or install.py can silently reopen the path.
  Proof (missing at integration-with-fixtures): tests/integration/test_install_local_bundle_e2e.py::test_install_zip_path_traversal_rejected_with_usage_error -- proves: apm install on a path-traversal zip exits non-zero and shows user-actionable error [secure-by-default]

• [recommended] export_plugin_bundle(archive=True, archive_format="tar.gz") section 15 has only dry-run test; no test verifies the actual .tar.gz file is written at src/apm_cli/bundle/plugin_exporter.py
  The live tar.gz branch in plugin_exporter.py section 15 is covered only by dry_run=True. Wrong argument order or transposed path would not be caught.
  Proof (missing at unit): tests/unit/test_plugin_exporter.py::TestArchive::test_archive_tar_gz -- proves: apm pack --archive --archive-format tar.gz via plugin format produces readable .tar.gz [portability-by-manifest]

• [nit] _bundle_size_suffix() KiB and MiB formatting branches have no test at src/apm_cli/commands/pack.py
  Proof (missing at unit): tests/unit/commands/test_pack_cli_surface.py::TestBundleSizeSuffix::test_kib_formatting

Performance Expert

• [recommended] sorted(rglob()) materializes full path list before first archive write -- streaming regression vs old tarfile.add() at src/apm_cli/utils/archive.py
  Old tarfile.add() did an internal os.walk-based streaming walk with no upfront materialization. sorted(rglob()) exhausts the generator and builds a list before any I/O; latency cliff at 5000+ files. Benefit: deterministic lexicographic order for bit-reproducible archives. Consider streaming heapq.merge variant if bundle sizes grow beyond a few thousand files.

• [recommended] compresslevel=9 in write_zip_archive costs 2-3x CPU for <3% ratio gain on text-heavy bundles at src/apm_cli/utils/archive.py
  Level 9 vs level 6: 2-5% smaller output, 2-3x longer compression CPU. For a 5MB skill bundle: ~75ms extra per pack invocation.
  Suggested: Change compresslevel=9 to compresslevel=6 (zlib sweet spot, matches zip(1) default on most platforms)

• [recommended] ensure_path_within() resolves dest_root once per member even though dest_root is constant across extraction loop at src/apm_cli/utils/archive.py
  dest_root.resolve() called for every member: 10,000 wasted resolve() syscalls at max-entries limit = ~80ms overhead.
  Suggested: Cache resolved_base = dest_root.resolve() outside the loop in safe_extract_zip.

• [nit] ZIP extract chunk size increased from 64KB to 1MB on hot download path -- positive change, cuts Python loop iterations 16x for large members.

• [nit] ZIP archives 30-130% larger than tar.gz for text-heavy bundles -- correctly documented in CHANGELOG, escape hatch exists, no action needed.

Auth Expert -- inactive

No auth surfaces touched. The only registry/client.py delta is Content-Type MIME type (application/gzip -> application/zip) and a cosmetic parameter rename -- neither affects how APM authenticates to any remote host.